Crate eax

source ·
Expand description

EAX: Authenticated Encryption and Associated Data (AEAD) cipher based on AES in counter mode.

§Usage

Simple usage (allocating, no associated data):

use aes::Aes256;
use eax::{
    aead::{Aead, KeyInit, OsRng, generic_array::GenericArray},
    Eax, Nonce
};

pub type Aes256Eax = Eax<Aes256>;

let key = Aes256Eax::generate_key(&mut OsRng);
let cipher = Aes256Eax::new(&key);
let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message
let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref())?;
let plaintext = cipher.decrypt(nonce, ciphertext.as_ref())?;
assert_eq!(&plaintext, b"plaintext message");

§In-place Usage (eliminates alloc requirement)

This crate has an optional alloc feature which can be disabled in e.g. microcontroller environments that don’t have a heap.

The AeadInPlace::encrypt_in_place and AeadInPlace::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Note that if you enable the heapless feature of this crate, you will receive an impl of aead::Buffer for heapless::Vec (re-exported from the aead crate as aead::heapless::Vec), which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

use aes::Aes256;
use eax::Eax;
use eax::aead::{AeadInPlace, KeyInit, generic_array::GenericArray};
use eax::aead::heapless::Vec;

let key = GenericArray::from_slice(b"an example very very secret key.");
let cipher = Eax::<Aes256>::new(key);

let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message

let mut buffer: Vec<u8, 128> = Vec::new();
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
cipher.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
cipher.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

§Custom Tag Length

The tag for eax is usually 16 bytes long but it can be shortened if needed. The second generic argument of Eax can be set to the tag length:

use aes::Aes256;
use eax::Eax;
use eax::aead::{AeadInPlace, KeyInit, generic_array::GenericArray};
use eax::aead::heapless::Vec;
use eax::aead::consts::{U8, U128};

let key = GenericArray::from_slice(b"an example very very secret key.");
let cipher = Eax::<Aes256, U8>::new(key);

let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message

let mut buffer: Vec<u8, 128> = Vec::new();
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
let tag = cipher.encrypt_in_place_detached(nonce, b"", &mut buffer).expect("encryption failure!");

// The tag has only 8 bytes, compared to the usual 16 bytes
assert_eq!(tag.len(), 8);

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
cipher.decrypt_in_place_detached(nonce, b"", &mut buffer, &tag).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports§

Modules§

  • online
    Online1 variant of the EAX mode.

Structs§

  • Eax
    EAX: generic over an underlying block cipher implementation.
  • Error
    Error type.

Constants§

  • A_MAX
    Maximum length of associated data
  • C_MAX
    Maximum length of ciphertext
  • P_MAX
    Maximum length of plaintext

Traits§

  • AeadCore
    Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
  • AeadInPlace
    In-place stateless AEAD trait.
  • KeyInit
    Types which can be initialized from key.
  • KeySizeUser
    Types which use key for initialization.

Type Aliases§